/*
 * Scaffold Application Framework
 *
 * Copyright (c) 2010 Sii Sp. z o.o. All rights reserved.
 */
package com.rstrulak.core.dao;

import java.util.List;
import java.util.Map;

import com.rstrulak.constant.GenericFilter;
import com.rstrulak.constant.PageInfo;
import com.rstrulak.constant.PresentationInfo;
import com.rstrulak.constant.SortInfo;

/**
 * Generic Data Access Object with most common CRUD methods. Extend this
 * interface if you want typesafe DAO's for your domain objects.
 * 
 * @param <T> persistent type class
 * @param <PK> primary key for the persistent type
 * 
 * @author Jakub Ciechan
 * @author Wojciech Kochman
 * @version 1.1
 */
public interface GenericDao<T, PK extends java.io.Serializable> {

    /**
     * Generic method to persist an object.
     * 
     * @param object - the object to save
     * @return primary key assigned to the persisted object
     */
    PK save(T object);

    /**
     * Save changes made to an already persisted object.
     * 
     * @param object - object to update
     */
    void update(T object);

    /**
     * Saves or updates given object depending on its current state.
     * 
     * @param object - object to save or update
     */
    void saveOrUpdate(T object);

    /**
     * Convenience method to delete an object based on its id.
     * 
     * @param id - identifier (primary key) of the object to delete
     */
    void delete(PK id);

    /**
     * Permanently deletes the object from persistent storage.
     * 
     * @param object - object to delete
     */
    void delete(T object);

    /**
     * Retrieves an object based on its primary key identifier.
     * 
     * @param id - identifier (primary key) of the object to retrieve
     * @return populated object
     */
    T getById(PK id);

    /**
     * Convenience method to check if an object with a specified primary key
     * identifier exists.
     * 
     * @param id - identifier (primary key) of the object
     * @return - true if it exists, false if it doesn't
     */
    boolean exists(PK id);

    /**
     * Generic method used to get all objects of a particular type.
     * 
     * @return List of populated objects
     */
    List<T> getAll();

    /**
     * Generic method used to get all objects of a particular type including
     * paging. It pages the results list according to paging informations
     * contained in <tt>pageInfo</tt>. Also total records count is set in the
     * <tt>pageInfo</tt> parameter.
     * 
     * @param pageInfo - paging informations to apply, IN/OUT parameter
     * @return Paged list of populated objects
     */
    List<T> getAll(final PageInfo pageInfo);

    /**
     * Generic method used to get all objects of a particular type including
     * sorting. It sorts the results list according to sorting informations
     * contained in <tt>sortInfo</tt>.
     * 
     * @param sortInfo - sorting informations to apply, IN parameter
     * @return Sorted list of populated objects
     */
    List<T> getAll(final SortInfo sortInfo);

    /**
     * Generic method used to get all objects of a particular type including
     * paging and sorting. It sorts the results list according to sorting
     * informations contained in <tt>sortInfo</tt> and pages it according to
     * paging informations contained in <tt>pageInfo</tt>. Also total records
     * count is set in the <tt>pageInfo</tt> parameter.
     * 
     * @param pageInfo - paging informations to apply, IN/OUT parameter
     * @param sortInfo - sorting informations to apply, IN parameter
     * @return Paged and sorted list of populated objects
     */
    List<T> getAll(final PageInfo pageInfo, final SortInfo sortInfo);

    /**
     * Generic method used to get all objects of a particular type including
     * paging and sorting. It applies to the results sorting and paging
     * informations contained in <tt>presentationInfo</tt> parameter.
     * 
     * @param presentationInfo - paging and/or sorting informations to apply,
     * results count and pages number is returned in presentationInfo.pageInfo
     * object
     * @return Paged and sorted list of populated objects
     */
    List<T> getAll(final PresentationInfo presentationInfo);

    /**
     * Generic method used to get all objects of a particular type including
     * multi filed filtering, paging and sorting. It applies to the results
     * sorting and paging informations contained in <tt>presentationInfo</tt>
     * parameter.
     * 
     * @param filter the {@link GenericFilter}
     * @param presentationInf paging and/or sorting informations to apply,
     * results count and pages number is returned in presentationInfo.pageInfo
     * @return
     */
    List<T> getAll(final GenericFilter filter, final PresentationInfo presentationInfo);

    /**
     * Retrieves a list of objects based on a query.
     * 
     * @param query - query to use
     * @return List of objects found
     */
    List<T> findByQuery(String query);

    /**
     * Retrieves a list of objects based on a named query.
     * 
     * @param queryName - query name of the named query
     * @param queryParams - a map of the query parameter names and the values
     * @return List of objects found
     */
    List<T> findByNamedQuery(String queryName, Map<String, Object> queryParams);

    /**
     * Gets the number of items in the result.When filter is not null returns
     * the number of filtered result otherwise all rows count.
     * 
     * @param filter the {@link GenericFilter}
     * @return number of results
     */
    int getResultCount(GenericFilter filter);
}
